package com.usbserial.scale.adapter;

import com.usbserial.core.SerialConfig;
import com.usbserial.core.SerialPort;
import com.usbserial.core.UsbSerialDeviceInfo;
import com.usbserial.exception.ParseException;
import com.usbserial.exception.UsbSerialException;
import com.usbserial.scale.ScaleData;

/**
 * 电子秤适配器接口
 * 每个具体设备型号需要实现此接口
 *
 * 职责：
 * - 识别和匹配特定设备
 * - 解析设备特定的数据协议
 * - 提供设备推荐的串口配置
 * - 发送设备特定的控制命令
 */
public interface ScaleAdapter {

    /**
     * 获取适配器名称
     *
     * @return 适配器的可读名称，例如 "Aclas OS2X Adapter"
     */
    String getName();

    /**
     * 获取支持的设备标识符
     * 用于设备匹配
     *
     * @return 设备标识符，包含制造商、型号、VID/PID等信息
     */
    ScaleDeviceIdentifier getDeviceIdentifier();

    /**
     * 初始化适配器
     * 在适配器创建后立即调用，用于执行设备特定的初始化
     *
     * @param port 已打开的串口连接
     * @param deviceInfo 设备信息
     * @throws UsbSerialException 初始化失败时抛出
     */
    void initialize(SerialPort port, UsbSerialDeviceInfo deviceInfo) throws UsbSerialException;

    /**
     * 解析原始数据为电子秤数据
     * 这是适配器的核心功能，实现设备特定的协议解析
     *
     * @param rawData 从串口接收的原始字节数据
     * @return 解析后的电子秤数据（重量、单位、状态等）
     * @throws ParseException 数据格式无效或解析失败时抛出
     */
    ScaleData parseData(byte[] rawData) throws ParseException;

    /**
     * 发送命令到电子秤
     * 不同设备支持的命令可能不同，不支持的命令应抛出异常
     *
     * @param command 命令类型
     * @param params 命令参数（可选）
     * @throws UsbSerialException 命令发送失败时抛出
     * @throws UnsupportedOperationException 设备不支持该命令时抛出
     */
    void sendCommand(ScaleCommand command, Object... params) throws UsbSerialException;

    /**
     * 获取推荐的串口配置
     * 返回该设备型号的最佳串口参数（波特率、数据位、停止位、校验位等）
     *
     * @return 推荐的串口配置
     */
    SerialConfig getRecommendedConfig();

    /**
     * 释放适配器资源
     * 在适配器不再使用时调用，用于清理资源、关闭连接等
     */
    void release();

    /**
     * 获取适配器版本
     * 用于调试和兼容性管理
     *
     * @return 适配器版本号，例如 "1.0.0"
     */
    String getVersion();
}
